home *** CD-ROM | disk | FTP | other *** search
/ A.C.E. 3 / ACE CD 3.iso / files / utils / aplay200.lha / APlayer / Files / Developer.lha / Rexxtools / Doc / Rexxtools.doc < prev   
Text File  |  1994-10-26  |  12KB  |  358 lines
  1. TABLE OF CONTENTS
  2.  
  3. rexxtools.library/rxFreeARexx
  4. rexxtools.library/rxGetARexxMsg
  5. rexxtools.library/rxGetPortName
  6. rexxtools.library/rxGetSignals
  7. rexxtools.library/rxInitARexx
  8. rexxtools.library/rxParseARexx
  9. rexxtools.library/rxReplyARexxMsg
  10. rexxtools.library/rxSendARexxMsg
  11. rexxtools.library/rxSetARexxLastError
  12. rexxtools.library/rxToNumber
  13. rexxtools.library/rxToString
  14.  
  15. rexxtools.library/rxFreeARexx                 rexxtools.library/rxFreeARexx
  16.  
  17.   NAME  rxFreeARexx()
  18.  
  19.     rxFreeARexx (rexxhd);
  20.  
  21.     void rxFreeARexx (APTR);
  22.              -36       A1
  23.  
  24.   DESCRIPTION
  25.     This  function will close the rexx handler. It's fully error checked so
  26.     you  can  pass  a NULL to this routine, which means it will do nothing.
  27.     This is useful if you want to use the rexx handler blindly.
  28.  
  29.   INPUTS
  30.     rexxhd - this  is  the  rexx  handler  you  got  from the rxInitARexx()
  31.              function.
  32.  
  33.   SEE ALSO
  34.     rxInitARexx()
  35.  
  36. rexxtools.library/rxGetARexxMsg             rexxtools.library/rxGetARexxMsg
  37.  
  38.   NAME  rxGetARexxMsg()
  39.  
  40.     rmsg = rxGetARexxMsg (rexxhd);
  41.  
  42.     APTR rxGetARexxMsg (APTR);
  43.      D0       -54        A1
  44.  
  45.   DESCRIPTION
  46.     This  function  will return the next ARexx message. If it returns NULL,
  47.     it  means  that  there  isn't any message or ARexx is not around. If it
  48.     returns  REXX_RETURN_ERROR,  it  means that a message sent to ARexx via
  49.     the rxSendARexxMsg() has returned an error.
  50.  
  51.   INPUTS
  52.     rexxhd - this  is  the  rexx  handler  you  got  from the rxInitARexx()
  53.              function.
  54.  
  55.   RESULT
  56.     rmsg   - this is a RexxMsg message pointer, NULL or REXX_RETURN_ERROR.
  57.  
  58.   SEE ALSO
  59.     rxReplyARexxMsg(), rxSetARexxLastError()
  60.  
  61. rexxtools.library/rxGetPortName             rexxtools.library/rxGetPortName
  62.  
  63.   NAME  rxGetPortName()
  64.  
  65.     name = rxGetPortName (rexxhd);
  66.  
  67.     APTR rxGetPortName (APTR);
  68.      D0       -42        A1
  69.  
  70.   DESCRIPTION
  71.     This function returns a pointer to the name of the ARexx port. The name
  72.     is  based  on the AppBaseName plus an invocation number if you have set
  73.     the  count flag when you made the port with the rxInitARexx() function.
  74.     If you haven't got an ARexx port, it will return NULL.
  75.  
  76.   INPUTS
  77.     rexxhd - this  is  the  rexx  handler  you  got  from the rxInitARexx()
  78.              function.
  79.  
  80.   RESULT
  81.     name   - a  pointer  to  your port name or NULL. Note that this is read
  82.              only, so do not try to change it.
  83.  
  84. rexxtools.library/rxGetSignals               rexxtools.library/rxGetSignals
  85.  
  86.   NAME  rxGetSignals()
  87.  
  88.     signals = rxGetSignals (rexxhd);
  89.  
  90.     ULONG rxGetSignals (APTR);
  91.      D0       -48        A1
  92.  
  93.   DESCRIPTION
  94.     This function returns the signal bit mask that is needed for your ARexx
  95.     port.  This  should  be combined with other signal masks to produce the
  96.     argument  to  the  Wait() call. This returns NULL if there is no signal
  97.     mask.
  98.  
  99.   INPUTS
  100.     rexxhd  - this  is  the  rexx  handler  you  got from the rxInitARexx()
  101.               function.
  102.  
  103.   RESULT
  104.     signals - the signal bit mask.
  105.  
  106. rexxtools.library/rxInitARexx                 rexxtools.library/rxInitARexx
  107.  
  108.   NAME  rxInitARexx()
  109.  
  110.     rexxhd = rxInitARexx (name, extension, flags, taglist);
  111.  
  112.     APTR rxInitARexx (APTR, APTR, ULONG, struct TagItem *);
  113.      D0      -30       A1    A2     D0          A0
  114.  
  115.   DESCRIPTION
  116.     This  function  will  initialize  a  rexx  handler  structure. The rexx
  117.     handler structure is much like a file handler, since it will be used in
  118.     all  the  other  functions.  All the other functions will automatically
  119.     test  the rexx handler before doing anything, so you don't have to test
  120.     the  result of this function. You can blindly use the result in all the
  121.     other  functions.  If  ARexx is not availble on your system, it wont do
  122.     anything.
  123.  
  124.   INPUTS
  125.     name      - this is a pointer to a NULL terminated string with the port
  126.                 name you want to use.
  127.  
  128.     extension - this is a pointer to a NULL terminated string with the file
  129.                 extension  you  want to use with your ARexx macros. If this
  130.                 is NULL, "REXX" (notice that you shouldn't type the leading
  131.                 ".") will be used.
  132.  
  133.     flags     - This  is  a longword with some flags. Each bit represents a
  134.                 flag. See below for a description of them all.
  135.  
  136.     taglist   - a pointer to a array of tags (currently always NULL).
  137.  
  138.   FLAGS
  139.     IARXF_PortCount
  140.       Set this to zero if you want a unique port. If it's set, you will get
  141.       an  invocation number at the end of the portname. This can be used if
  142.       you want to use multiply copies of the same program.
  143.  
  144.   TAGS
  145.     No tags defined yet.
  146.  
  147.   RESULT
  148.     rexxhd    - This  is a rexx handler you'll have to use in all the other
  149.                 functions in this library or NULL if an error occurs.
  150.  
  151.   SEE ALSO
  152.     rxFreeARexx()
  153.  
  154. rexxtools.library/rxParseARexx               rexxtools.library/rxParseARexx
  155.  
  156.   NAME  rxParseARexx()
  157.  
  158.     success = rxParseARexx (rexxhd, rmsg, cmdtab, jmptab, userdata,
  159.                             taglist);
  160.  
  161.     short rxParseARexx (APTR, APTR, APTR, APTR, LONG, struct TagItem *);
  162.       D0       -78       A1    A2    A3    A4    D0         A0
  163.  
  164.   DESCRIPTION
  165.     This  function  can  be  used  to  parse  the  message you got from the
  166.     rxGetARexxMsg()  function, to see if it's one of your own commands. You
  167.     have  to  make some special tables with all your commands and where you
  168.     want to go, if it finds one. The commando table has to build like this:
  169.  
  170.     - First a byte indicating the length of your command.
  171.     - Then  your  command  in  a  string  (Note  that  it  may  not be NULL
  172.       terminated).
  173.     - At last how many arguments you want for your command (max 8).
  174.     - New length to the next command or NULL for end.
  175.  
  176.     You  also  have  to  make  a jump table. This table is just a couple of
  177.     longwords,  one for each command. Every longword should be a pointer to
  178.     a routine you want to run on the specific command.
  179.  
  180.     When  you routine is called, you will in A1 have the userdata and in A6
  181.     the rexxtools library base address. In A0 you will get a pointer to the
  182.     first  argument.  Every  argument  is  NULL terminated and will use 256
  183.     bytes.  That  means  to get the second argument, you have to add 256 to
  184.     the  pointer and to get the third argument you have to add 2*256 to the
  185.     pointer etc.
  186.  
  187.     You'll have to reply the message in your command routine. This function
  188.     will  automatic  reply  the  message if some error occurs, like unknown
  189.     command.
  190.  
  191.   INPUTS
  192.     rexxhd   - this  is  the  rexx  handler  you got from the rxInitARexx()
  193.                function.
  194.  
  195.     rmsg     - this  is  the ARexx message you got from the rxGetARexxMsg()
  196.                function.
  197.  
  198.     cmdtab   - this is a pointer to a command table.
  199.  
  200.     jmptab   - this is a pointer to a jump table.
  201.  
  202.     userdata - this is your own data. It will be in A1 when your command is
  203.                called via the jump table.
  204.  
  205.     taglist  - a pointer to a array of tags (currently always NULL).
  206.  
  207.   TAGS
  208.     No tags defined yet.
  209.  
  210.   RESULT
  211.     success  - this will be NULL if some error occures.
  212.  
  213.   SEE ALSO
  214.     rxGetARexxMsg(), rxReplyARexxMsg(), rxSetARexxLastError()
  215.  
  216. rexxtools.library/rxReplyARexxMsg         rexxtools.library/rxReplyARexxMsg
  217.  
  218.   NAME  rxReplyARexxMsg()
  219.  
  220.     rxReplyARexxMsg (rexxhd, rmsg, result, error);
  221.  
  222.     void rxReplyARexxMsg (APTR, APTR, APTR, LONG);
  223.               -60          A1    A0    A2    D0
  224.  
  225.   DESCRIPTION
  226.     This  function  replies  the ARexx message "rmsg" you have got from the
  227.     rxGetARexxMsg()   function.  The  "result"  is  a  pointer  to  a  NULL
  228.     terminated  result  string that will be returned via OPTIONS RESULTS in
  229.     the RESULT ARexx variable. If you have no result, set this to NULL. The
  230.     "error"  is  the  error severity level. If this is 0, the result string
  231.     will be returned, if this is non-zero, the error level will be returned
  232.     in RC.
  233.  
  234.   INPUTS
  235.     rexxhd - this  is  the  rexx  handler  you  got  from the rxInitARexx()
  236.              function.
  237.  
  238.     rmsg   - this  is  the  ARexx  message you got from the rxGetARexxMsg()
  239.              function.
  240.  
  241.     result - this is a pointer to a NULL terminated result string or NULL.
  242.  
  243.     error  - this is an error severity level code or NULL for no error.
  244.  
  245.   SEE ALSO
  246.     rxGetARexxMsg(), rxSetARexxLastError()
  247.  
  248. rexxtools.library/rxSendARexxMsg           rexxtools.library/rxSendARexxMsg
  249.  
  250.   NAME  rxSendARexxMsg()
  251.  
  252.     success = rxSendARexxMsg (rexxhd, command, stringfile);
  253.  
  254.     short rxSendARexxMsg (APTR, APTR, short);
  255.      D0        -66         A1    A0     D0
  256.  
  257.   DESCRIPTION
  258.     This  function will send a string to ARexx. It sets the default host to
  259.     your  application  and  sets  the RXFB_STRING bit in the message if the
  260.     "stringfile"  is true. That means, you can set this to true if you want
  261.     to  send  an  ARexx command or false if you want to start a macro. This
  262.     function will return false if the message was not sent.
  263.  
  264.   INPUTS
  265.     rexxhd     - this  is  the  rexx handler you got from the rxInitARexx()
  266.                  function.
  267.  
  268.     command    - this  is  a  pointer  to a NULL terminated string with the
  269.                  command or the name of the macro you want to run.
  270.  
  271.     stringfile - this  flag indicates if it's a command or a macro you want
  272.                  to run.
  273.  
  274.   RESULT
  275.     success    - this will be NULL if some error occurs.
  276.  
  277. rexxtools.library/rxSetARexxLastError rexxtools.library/rxSetARexxLastError
  278.  
  279.   NAME  rxSetARexxLastError()
  280.  
  281.     success = rxSetARexxLastError (rexxhd, rmsg, errorstring);
  282.  
  283.     short rxSetARexxLastError (APTR, APTR, APTR);
  284.       D0         -72            A1    A0    A2
  285.  
  286.   DESCRIPTION
  287.     This  function uses the RVI (Rexx Variable Interface) to set a variable
  288.     named  <AppBaseName>.LASTERROR  to the "errorstring". This is where the
  289.     error  message  should  go  if there is an error. This function returns
  290.     NULL if this fails for any reason.
  291.  
  292.   INPUTS
  293.     rexxhd      - this  is  the rexx handler you got from the rxInitARexx()
  294.                   function.
  295.  
  296.     rmsg        - this   is   the   ARexx   message   you   got   from  the
  297.                   rxGetARexxMsg() function.
  298.  
  299.     errorstring - this  is  a  pointer to a NULL terminated string with the
  300.                   error message.
  301.  
  302.   RESULT
  303.     success     - this will be NULL if some error occurs.
  304.  
  305. rexxtools.library/rxToNumber                   rexxtools.library/rxToNumber
  306.  
  307.   NAME  rxToNumber()
  308.  
  309.     number = rxToNumber (rexxhd, string);
  310.  
  311.     LONG rxToNumber (APTR, APTR);
  312.      D0     -84       A1    A0
  313.  
  314.   DESCRIPTION
  315.     This  function  can  be  used  if  you want to convert an argument to a
  316.     binary  number.  It  will  just  convert  your ASCII string to a signed
  317.     number.
  318.  
  319.   INPUTS
  320.     rexxhd - this  is  the  rexx  handler  you  got  from the rxInitARexx()
  321.              function.
  322.  
  323.     string - this  is a pointer to a NULL terminated string with the number
  324.              to want to convert.
  325.  
  326.   RESULT
  327.     number - this is a 32 bit signed number.
  328.  
  329.   SEE ALSO
  330.     rxToString()
  331.  
  332. rexxtools.library/rxToString                   rexxtools.library/rxToString
  333.  
  334.   NAME  rxToString()
  335.  
  336.     rxToString (rexxhd, number, buffer);
  337.  
  338.     void rxToString (APTR, LONG, APTR);
  339.             -90       A1    D0    A0
  340.  
  341.   DESCRIPTION
  342.     This  function  can be used if you want to convert a number to a result
  343.     string. It will just convert your signed longword to an NULL terminated
  344.     ASCII string.
  345.  
  346.   INPUTS
  347.     rexxhd - this  is  the  rexx  handler  you  got  from the rxInitARexx()
  348.              function.
  349.  
  350.     number - this is your signed longword you want to convert.
  351.  
  352.     buffer - this  is  a  pointer  to  a buffer where you want to store the
  353.              string.
  354.  
  355.   SEE ALSO
  356.     rxToNumber()
  357.  
  358.